msToolJS scripting plugin for MilkShape3D

By Ulf Öhlén
ulf_ohlen@hotmail.com

Overview

This plugin provides JavaScript support for MilkShape 3D 1.6.*. It wraps the MilkShape SDK in a hierarchy of JavaScript objects that can be manipulated with scripts.

The purpose of this plugin is to make it easier to add custom behaviour to MilkShape, without going through the process of writing a plugin. JavaScript is normally considered a far less complex language than C/C++. Also, no compiler is needed. However, the support for custom UIs is at the moment quite limited.

This document is only intended as a quick reference to the object model used. For info on the JavaScript language and standard objects, please refer to a JavaScript manual. See the samples for an example on how to use the plugin. I suggest reading the Report.js sample, as it makes use of the entire object hierarchy.

Installation

Copy these files to your MilkShape directory:

- msToolJS.dll		The plugin
- msToolJS.htm		This file
- js32.dll		Mozilla's JavaScript engine (SpiderMonkey)
Samples (optional):
- JSSamples\Report.js		Creates a report of the model
- JSSamples\Spikey.js		Converts each triangle into a spike
- JSSamples\Unweld.js		Unwelds the vertices in the model
- JSSamples\Tetraeder.js		Creates a new tetraeder mesh
- JSSamples\Octaeder.js		Creates a new octaeder mesh

The plugin will also create this file when executed:

- msToolJS.ini

Plugin settings

Global stuff
Global objects	Type	Description
model	Model	The one and only Model instance. Changes to this object will show in MilkShape.

Constants	Type	Description
eSelected	int	Selected flag
eSelected2	int	Selected flag (?)
eHidden	int	Hidden flag
eDirty	int	Dirty flag
eAveraged	int	Averaged flag
eUnused	int	?

Functions	Description
write(message, ...)	Writes one or more values to the console.
writeln(message, ...)	Writes one or more values to the console. Ends with a new line.
clearConsole()	Clear the console.
alert(message)	Displays a messagebox
confirm(message)	Displays a confirmation dialog box
showOpenDlg(dialogTitle, filter, initialDir, defaultFile, defaultExt)	Displays a file open dialog. Returns the file path or null if cancelled. Example: showOpenDlg("Open File", "Text\|*.txt\|\|", "C:\\Blask", "Default.txt", "txt")
showSaveDlg(dialogTitle, filter, initialDir, defaultFile, defaultExt)	Displays a file save dialog. Returns the file path or null if cancelled. Example: showSaveDlg("Save File", "Text\|*.txt\|\|", "C:\\Blask", "Default.txt", "txt")
prompt(message, default, title)	Displays a dialog that prompts the user for a string.
gc()	Runs the garbage collector

Class: Bone
Properties	Type	Description
flags	int
name	String
parentName	String
position	Vec3
rotation	Vec3
positionKeys	Collection of PositionKey
rotationKeys	Collection of RotationKey

Functions	Description
Bone()	Constructor.

Class: Collection	Collection class for storing a number of objects. Each instance is associated with a certain object type.
Properties	Type	Description
operator []	Object	Sets/gets an item in the collection
length	int	Number of items

Functions	Description
push(object, ...)	Adds one or more items in the back of the collection. Returns a reference to the last item added.
insert(object, index)	Adds an item at the specified index.
erase(first, count)	Removes one or more items.
clear()	Empties the collection

Class: File	Class for reading/writing files on disk.
Static open flags	Type	Description
APP	int	Flag: Opens an output file for appending.
ATE	int	Flag: Opens an existing file and seeks the end.
IN	int	Flag: Opens an input file.
OUT	int	Flag: Opens an output file.
TRUNC	int	Flag: Opens a file and deletes the old file, if it already exists.
BINARY	int	Flag: Opens a file in binary mode. Text mode is default.
curDir	String	Get/set the current directory

Properties	Type	Description
path	String	Full path of the open file
name	String	Name of the open file
canRead	Boolean	Returns true if file is open for reading
canWrite	Boolean	Returns true if file is open for writing
isOpen	Booleang	Returns true if file is open
mode	int	Original open flags
size	int	Length of the file (not implemented)
position	int	Read/write position (not implemented)
eof	Boolean	Checks for End of file

Functions	Description
File(fileName, flags)	Constructor. Optionally opens a file.
open(fileName, flags)	Open a file.
close()	Close the file.
read(bytes)	Read a bytes long string from the file
readln()	Read a line from the file
write(arg, ...)	Write a number of arguments to the file

Static functions	Description
exists(fileName)	Returns true if specified file exists.
copy(srcName, destPath)	Copy an external file
del(fileName)	Delete an external file
move(srcName, destName)	Move/rename an external file.
mkDir(path)	Create a directory.
created(fileName)	Returns creation date for a file (not implemented)
modified(fileName)	Returns modified date for a file (not implemented)
attrib(fileName)	Returns file attributes (not implemented)
fileSize(fileName)	Returns file size (not implemented)

Class: Material
Properties	Type	Description
flags	int
name	String
ambient	Vec4
diffuse	Vec4
specular	Vec4
emissive	Vec4
shininess	double
transparency	double
diffuseTexture	String
alphaTexture	String
nName	int

Functions	Description
Material(name)	Constructor. Parameters are optioinal.

Class: Mesh
Properties	Type	Description
flags	int
name	String
materialIndex	int
vertices	Collection of Vertex
normals	Collection of Vec3
triangles	Collection of Triangle

Functions	Description
Mesh(name, materialIndex, flags)	Constructor. Parameters are optioinal.

Class: Model
Properties	Type	Description
meshes	Collection of Mesh
materials	Collection of Material
bones	Collection of Bone
frame	int
totalFrames	int
position	Vec3
rotation	Vec3

Class: PositionKey
Properties	Type	Description
time	double
position	Vec3

Functions	Description
PositionKey(time, position)	Constructor. Parameters are optional

Class: RotationKey
Properties	Type	Description
time	double
rotation	Vec3

Functions	Description
RotationKey(time, rotation)	Constructor. Parameters are optional

Class: Triangle
Properties	Type	Description
flags	int
vertexIndices	int[3]
normalIndices	int[3]
normal	Vec3
smoothingGroup	int

Functions	Description
Triangle(vertexIndices, normalIndices, flags)	Constructor. Parameters are optional

Class: Vec2
Properties	Type	Description
x	double
y	double

Functions	Description
Vec2(x, y)	Constructor. Parameters are optional.

Class: Vec3
Properties	Type	Description
x	double
y	double
z	double

Functions	Description
Vec3(x, y, z)	Constructor. Parameters are optional.
length()	Returns the length of a vector.
length2()	Returns the squared length of a vector.
normalize(newLength)	Normalize a vector. Default newLength=1.

Static functions	Description
crossProd(v1, v2)	Returns the cross product of two Vec3's.

Class: Vec4
Properties	Type	Description
x	double
y	double
z	double
w	double

Functions	Description
Vec4(x, y, z, w)	Constructor. Parameters are optional.

Class: Vertex
Properties	Type	Description
flags	int
vertex	Vec3
u	double
v	double
boneIndex	int

Functions	Description
Vertex(x, y, z, u, v, boneIndex, flags)	Constructor. Parameters are optional

msToolJS scripting plugin for MilkShape3D

Overview

Installation

Global stuff

Class: Bone

Class: Collection

Class: File

Class: Material

Class: Mesh

Class: Model

Class: PositionKey

Class: RotationKey

Class: Triangle

Class: Vec2

Class: Vec3

Class: Vec4

Class: Vertex